

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Flow &mdash; IVRE  documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="../_static/graphviz.css?v=4ae1632d" />

  
      <script src="../_static/jquery.js?v=5d32c60e"></script>
      <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="../_static/documentation_options.js?v=5929fcd5"></script>
      <script src="../_static/doctools.js?v=9bcbadda"></script>
      <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Web User Interface" href="web-ui.html" />
    <link rel="prev" title="Passive" href="passive.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            IVRE
              <img src="../_static/logo.png" class="logo" alt="Logo"/>
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul>
<li class="toctree-l1"><a class="reference internal" href="../overview/index.html">Overview</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../install/index.html">Installation</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Usage</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="use-cases.html">Some use cases</a></li>
<li class="toctree-l2"><a class="reference internal" href="active-recon.html">Active recon</a></li>
<li class="toctree-l2"><a class="reference internal" href="passive.html">Passive</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Flow</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#data-insertion">Data insertion</a></li>
<li class="toctree-l4"><a class="reference internal" href="#data-exploration">Data exploration</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="web-ui.html">Web User Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="kibana.html">IVRE with Kibana</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../dev/index.html">Development</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Licenses:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../license.html">IVRE: GPL v3</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license-external.html">Licenses for external files</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">IVRE</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Usage</a></li>
      <li class="breadcrumb-item active">Flow</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/usage/flow.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="flow">
<h1>Flow<a class="headerlink" href="#flow" title="Link to this heading"></a></h1>
<p>IVRE flow is a beta feature meant to analyze network flows between
hosts. It can be seen as:</p>
<ul class="simple">
<li><p>a recon tool for the case of an unknown network (hence its apparition
in IVRE/DRUNK)</p></li>
<li><p>a cartography tool to get a better understanding of a supposedly
known network (but there is no such thing as a “known network”)</p></li>
<li><p>a monitoring tool to spot unwanted flows in your network</p></li>
</ul>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
<section id="data-insertion">
<h3>Data insertion<a class="headerlink" href="#data-insertion" title="Link to this heading"></a></h3>
<p>There are two tools for data insertion, the first is based on Zeek
(previously known as Bro):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>zeek<span class="w"> </span>-r<span class="w"> </span>capture_file.pcap
$<span class="w"> </span>ivre<span class="w"> </span>zeek2db<span class="w"> </span>./*.log
$<span class="w"> </span>ivre<span class="w"> </span>flowcli
</pre></div>
</div>
<p>The second can take either argus logs or netflow logs:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>argus<span class="w"> </span>-m<span class="w"> </span>-r<span class="w"> </span>capture_file.pcap<span class="w"> </span>-w<span class="w"> </span>flows.argus
$<span class="w"> </span>ivre<span class="w"> </span>flow2db<span class="w"> </span>flows.argus
</pre></div>
</div>
<p>Or:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>ivre<span class="w"> </span>flow2db<span class="w"> </span>flows.nfdump
</pre></div>
</div>
<p>Or:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>ivre<span class="w"> </span>flow2db<span class="w"> </span>-t<span class="w"> </span>iptables<span class="w"> </span>iptables-from-syslog.log
</pre></div>
</div>
<p>Any of these tools can be called with ‘–init’ to reinitialize the DB.</p>
</section>
<section id="data-exploration">
<h3>Data exploration<a class="headerlink" href="#data-exploration" title="Link to this heading"></a></h3>
<p>The main exploration tool are the CLI (<code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">flowcli</span></code>) and the Web UI
(<code class="docutils literal notranslate"><span class="pre">&lt;ivre-web-root&gt;/flow.html</span></code>).</p>
<section id="cli">
<h4>CLI<a class="headerlink" href="#cli" title="Link to this heading"></a></h4>
<p>You can access the CLI through <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">flowcli</span></code>. Features include:</p>
<ul class="simple">
<li><p>Searching for flows and nodes with filters (see the Flow Filters
section of this document)</p></li>
<li><p>Producing top values for given criteria</p></li>
<li><p>Plotting flows amounts over hours of days, on average.</p></li>
</ul>
<p>See <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">flowcli</span> <span class="pre">-h</span></code> for usage details.</p>
</section>
<section id="web-ui">
<h4>Web UI<a class="headerlink" href="#web-ui" title="Link to this heading"></a></h4>
<section id="overview">
<h5>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h5>
<p>The central view is a graph representing the network:</p>
<ul class="simple">
<li><p>nodes represent hosts; white ones represent hosts that have incoming
network flows, grey ones those who do not have any</p></li>
<li><p>edges represent network flows; same [proto, dport] couple will have
the same color</p></li>
</ul>
<p>Flows are aggregated by destination port (or code, for icmp), two
different connection from the same source to the same destination on the
same destination port (so called <code class="docutils literal notranslate"><span class="pre">dport</span></code>) but with different source
ports will be aggregated on the same edge.</p>
<p>On the bottom of the graph, there is a timeline, representing the amount
of different flows during some time ranges. This timeline can be played
by going to the <strong>Display</strong> pane.</p>
<p>On the left, there is a control pane with 3 tabs:</p>
<ul class="simple">
<li><p><strong>Explore:</strong> Allows to explore and reduce the dataset to display with
node-based or edge-based queries. See the next section for more
details. It also allows to navigate through the data (limit/skip) and
change the query mode. At the top of this pane, there is a count of
the flows, servers and clients matching the current query. Note that
servers can also be counted as clients if they have outgoing flows.</p></li>
<li><p><strong>Display:</strong> Allows to change the way data is displayed (size of
nodes and edges, timeline precision).</p></li>
<li><p><strong>Details:</strong> Details on the currently selected item.</p></li>
</ul>
</section>
<section id="interaction">
<h5>Interaction<a class="headerlink" href="#interaction" title="Link to this heading"></a></h5>
<p>Hover nodes and edges to display their basic properties in the
<strong>Details</strong> tab. Click on an edge or a node to query the database for
more information, including any associated metadata (for example DNS
queries happening on a network flow).</p>
<p>There are two ways of filtering the data:</p>
<ul class="simple">
<li><p>Right click on a node or edge and <code class="docutils literal notranslate"><span class="pre">Filter</span> <span class="pre">by</span></code>/<code class="docutils literal notranslate"><span class="pre">Filter</span> <span class="pre">out</span></code> by
attribute</p></li>
<li><p>Write filters yourself</p></li>
</ul>
<p>See the Flow Filter section of this document for more information on the
filter syntax.</p>
<p>The <strong>Display</strong> pane allows to change the size of nodes and edges based
on some criteria:</p>
<ul class="simple">
<li><p>On nodes, available keywords are <code class="docutils literal notranslate"><span class="pre">$in</span></code> and <code class="docutils literal notranslate"><span class="pre">$out</span></code>, to make the
size proportional to the number of incoming or outgoing flows of a
node.</p></li>
<li><p>On edges, a property can be specified (for example <code class="docutils literal notranslate"><span class="pre">scbytes</span></code>, the
number of bytes from the server to the client).</p></li>
</ul>
<p>Do not forget to increase the <code class="docutils literal notranslate"><span class="pre">Size</span> <span class="pre">scale</span></code> to make the result more
visible.</p>
<p>The <strong>Display</strong> pane also allows to change the amount of time slots to
represent on the timeline (capped by the actual time precision set in
<code class="docutils literal notranslate"><span class="pre">ivre.conf</span></code>). The timeline can also be played on the graph by clicking
the ‘Play timeline’ button.</p>
</section>
</section>
<section id="flow-filters">
<h4>Flow Filters<a class="headerlink" href="#flow-filters" title="Link to this heading"></a></h4>
<p>To write filters, the syntax is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>[!][ANY|ALL|ONE|LEN ][src.|dst.][meta.]&lt;attribute&gt; [&lt;operator&gt; &lt;value&gt;]
[OR &lt;other filter&gt;]
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">[src.|dst.]</span></code> part is only available for node filters.</p>
<p>The special keywords <code class="docutils literal notranslate"><span class="pre">ANY</span></code>, <code class="docutils literal notranslate"><span class="pre">ALL</span></code>, <code class="docutils literal notranslate"><span class="pre">ONE</span></code> and <code class="docutils literal notranslate"><span class="pre">LEN</span></code> are for
working with array attributes:</p>
<ul class="simple">
<li><p>ALL: matches if all the elements of the array fulfil the predicate</p></li>
<li><p>ANY: the same if any of the elements match</p></li>
<li><p>ONE: the same if exactly one of the elements match</p></li>
<li><p>LEN: the predicate will use the len of the array</p></li>
</ul>
<p>Some examples:</p>
<ul class="simple">
<li><p>Node filter <code class="docutils literal notranslate"><span class="pre">dst.addr</span> <span class="pre">=</span> <span class="pre">192.168.1.1</span></code> will match all the flows whose
destination is a host with address <code class="docutils literal notranslate"><span class="pre">192.168.1.1</span></code>.</p></li>
<li><p>Node filter <code class="docutils literal notranslate"><span class="pre">addr</span> <span class="pre">=~</span> <span class="pre">192\.168\.1\..*</span></code> will match all the flows that
come from or go to a host whose address matches the
<code class="docutils literal notranslate"><span class="pre">192\.168\.1\..*</span></code> regex (sorry, CIDR masks are on their way to be
implemented).</p></li>
<li><p>Edge filter <code class="docutils literal notranslate"><span class="pre">dport</span> <span class="pre">&gt;</span> <span class="pre">10000</span></code> will match all the flows with a
<code class="docutils literal notranslate"><span class="pre">dport</span></code> (destination port) above 10000. <code class="docutils literal notranslate"><span class="pre">!dport</span> <span class="pre">&lt;=</span> <span class="pre">10000</span></code> will
match the same flows plus the ones that do not have any destination
port.</p></li>
<li><p>Edge filter <code class="docutils literal notranslate"><span class="pre">meta.query</span> <span class="pre">=~</span> <span class="pre">.*google.*</span></code> will match all the flows
that have an associated metadata which have a <code class="docutils literal notranslate"><span class="pre">query</span></code> attribute
that match the <code class="docutils literal notranslate"><span class="pre">.*google.*</span></code> regex.</p></li>
<li><p>Edge filter <code class="docutils literal notranslate"><span class="pre">ANY</span> <span class="pre">sports</span> <span class="pre">&lt;</span> <span class="pre">1024</span></code> will match flows with at least one
source port &lt; 1024.</p></li>
<li><p>Edge filter <code class="docutils literal notranslate"><span class="pre">LEN</span> <span class="pre">sports</span> <span class="pre">=</span> <span class="pre">1</span></code> will match flows with only one known
source port.</p></li>
<li><p>Filter <code class="docutils literal notranslate"><span class="pre">ANY</span> <span class="pre">meta.answers</span> <span class="pre">=~</span> <span class="pre">.*example.com</span></code> will match any metadata
that contain an array attribute <code class="docutils literal notranslate"><span class="pre">answers</span></code> where at least one entry
matches <code class="docutils literal notranslate"><span class="pre">'.*example.com'</span></code>.</p></li>
</ul>
<p>Available operators are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">=</span></code> or <code class="docutils literal notranslate"><span class="pre">:</span></code> (equality)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">!=</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&lt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&lt;=</span></code>, <code class="docutils literal notranslate"><span class="pre">&gt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&gt;=</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">=~</span></code></p></li>
</ul>
</section>
</section>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="passive.html" class="btn btn-neutral float-left" title="Passive" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="web-ui.html" class="btn btn-neutral float-right" title="Web User Interface" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2011 - 2025, Pierre LALET.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>